home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Creative Computers
/
Creative Computers CD-ROM, Volume 1 (Legendary Design Technologies, Inc.)(1994).iso
/
commercial
/
legendary_design
/
invoiceit!
/
req.doc
< prev
next >
Wrap
Text File
|
1994-11-17
|
64KB
|
1,675 lines
The req.library is a run time re-entrant library that is designed
to make it easier for programmers to use powerful, easy to use
requesters for communicating with users. The requester library
includes such functions as a color requester, file requester, message
display requester and many functions to make the creation of gadgets
for your own custom requesters easier.
Req.library was written by Colin Fox (of Pyramyd Designs) and
Bruce Dawson (of CygnusSoft Software). Req.library is a freely
distributable library that may be used in commercial products without
paying any royalties. We encourage you to use the requester library
in all of your programs, to make them easier to write, and to use.
Req.library is not public domain. The requester library and all
documentation and example programs are all copyright 1989.
The requester library must be distributed with the documentation
file (req.doc), and the three include files (req.h, reqbase.h and
reqbase.i).
Req.library is dedicated to the programmers who make the Amiga
shine the way it was meant to.
OverView:
All of the req.library functions that bring up requesters allow
you two ways of specifying what screen you would like the requester to
appear on. The first way is the more efficient way, because you only
have to set it up once and then it takes care of things automatially.
There is a field in all process structures called the pr_WindowPtr.
This pointer is used by DOS to decide where to put it's requesters.
If pr_WindowPtr contains a zero, requesters go on the workbench
screen. If it contains the address of a window, then requesters go on
that window's screen. If it contains a negative one, then no DOS
requesters come up. The req.library requesters all use this variable,
if they are called from a process . However, if the pointer is -1,
the req.library functions do still appear, on the workbench screen.
The second way was put in mainly so that the requesters can be
called from tasks. Since a task does not have a process structure, it
also lacks a pr_WindowPtr. Therefore, all of the requester functions
which can be used from a task (currently everything except the file
requester) can be passed a window pointer, either as a parameter or as
an element in a structure. Important: This pointer takes precedence
over the pr_WindowPtr so if you wish the requesters to use the
pr_WindowPtr you must zero the window fields that the routines are
expecting. In the case of fields in a structure this can be easy as
long as you make sure your structure defaults to being zero
everywhere.
Setting the pr_WindowPtr is quite a simple matter. All you have
to do is do a FindTask((char *)0); which returns a pointer to your own
task and your own process (a task structure is the first element of a
process structure). Then you simply preserve the old value of
pr_WindowPtr (VERY IMPORTANT!!!) and put a window pointer into it.
eg:
/* Find my task. */
myprocess = (struct Process *)FindTask((char *)0);
oldwindowptr = myprocess->pr_WindowPtr;
myprocess->pr_WindowPtr = window;
or:
MOVE.L 4,A6
MOVE.L #0,A1
SYS FindTask ;Find my task.
MOVE.L D0,_myprocess
MOVE.L D0,A0
MOVE.L pr_WindowPtr(A0),_oldwindowptr
MOVE.L _window,pr_WindowPtr(A0)
Before your program exits it is VERY important that it restore the
previous value of pr_WindowPtr. If you don't, then your program will
work in some situations, but will BLOW UP in others. For example, if
you execute (without using the 'run' command) a program, which then
sets the pr_WindowPtr to point at one of its windows and the exits
without restoring it, then the next time a DOS requester tries to
appear... BOOM! The machine will probably crash as DOS tries to open
a requester on a now closed screen. Therefore, before leaving:
myprocess->pr_WindowPtr = oldwindowptr;
or:
MOVE.L _myprocess,A0
MOVE.L _oldwindowptr,pr_WindowPtr(A0)
One final note. The pr_WindowPtr field exists in the process
structure. This means that a task does not have this field.
Therefore, if you want to call one of the requester library functions
from a task, you will not be able to specify what screen you would
like the requester to appear on by setting the pr_WindowPtr field.
All of the functions that open requesters and can be called from a
task (the file requester/font requester is the only one that can't be
called froma task) have some other way of specifying which screen you
would like them to open on. They will have either have a field in the
structure which you must pass them or a parameter which can contain a
window pointer to one of the windows on your custom screen. If this
pointer is non-zero then it overrides the pr_WindowPtr field.
By opening the requester library, you not only gain access to all
of the functions documented below, but to some other goodies as well.
Req.library needs and therefore opens several other libraries,
including dos.library, intuition.library, graphics.library and the
console device. All of these pointers are stored in the ReqLib
structure which you get a pointer to when you open the req.library.
Therefore, you can save yourself a little bit of code by grabbing
these fields after opening the requester library. The only thing to
beware of is don't use these values after you have close the requester
library, because at that point there is no guarantee that they will
still be valid.
In addition to these libraries, the Images pointer in the req
library structure points to a set of ten small images (four arrows and
ssix letters) which have are guaranteed to be in chip memory. These
can be used if your program requires this type of images.
One thing to keep in mind when using the gadget creation routines
is that there isn't any way for us to check that you have passed us a
pointer to the correct size of buffer, so you _must_ make sure that
you are allocating the right amount of memory.
--------------------------------------------------------------
Here's a quick list of the functions available:
--------------------------------------------------------------
Center..................Center a new window over the mouse.
SetSize.................Prop gadget handling routines (32 bit)
SetLocation
ReadLocation
Format..................sprintf() format routine
SimpleRequest...........Starter gluecode to TextRequest- Single gadget
TwoGadRequest...........Starter gluecode to TextRequest- Two gadgets
FileRequester...........FileRequester routines
PurgeFiles
ColorRequester..........a colorrequester
MakeGadget..............Gadget creation routines
MakeString
MakeProp
MakeButton
MakeScrollBar...........3 part gadget; 2 arrows and a prop.
Horizontal or Vertical
LinkGadget..............Gadget creation routines that self-hook into
the newwindow
LinkStringGadget........gadget list.
LinkPropGadget
DrawBox.................Draw a box (x1y1)(x2y2) in one command
GetFontHeightAndWidth...return height and width of current font
RealTimeScroll..........scroll routine used in file requester
TextRequest.............Powerful requester function
GetString...............Get a line of text from the user
GetLong.................Get a signed long from the user
RawKeyToAscii...........Convert raw key to ascii
NewGetString A second point to GetString. Different way of
passing parameters.
----------------------------------------------------------------
NAME
Center
SYNOPSIS
Center( &nw, x, y)
A0 D0 D1
struct NewWindow *nw;
USHORT x,y;
DESCRIPTION
Center() is used to